🥳 New Feature 🥳 PlantUML visualization #1158

pdalfarr · 2024-07-05T08:49:48Z

The goal of this PR is to add the ability to dump a Spring stateMachine to PlanUML State Diagram format and to .png format 🥳

Features:

Diagram Visualization 👁️
Allow you to 'visualize' your Spring State Machine as .puml or .png !

Current transition Highlight 🎯
If a state machine is dumped at org.springframework.statemachine.StateContext.Stage.TRANSITION_END phase, a red arrow is used between the 'source' state and the 'target' state.
see

spring-statemachine/spring-statemachine-uml/src/main/java/org/springframework/statemachine/plantuml/PlantUmlWriterParameters.java

Lines 246 to 248 in 59df160

    
           public String getArrowColor(boolean isCurrentTransaction) { 
        
               return isCurrentTransaction ? "[#FF0000]" : ""; 
        
           }

Actions and Guards description 🪪
Support BeanAware for Actions and Guards, so bean names are used in diagram
-> much better than having labels like Action@0x1f4f5d1d
SpEL Expression support 🟰
Support for SpelExpressionAction and SpelExpressionGuard : SpEL expression is used as label.
Allow to 'tweak' the Diagram

Modifying PlantUML diagram settings 🎚️
Forcing Transition directions ➡️
Hiding some transitions 🙈
Adding a text note on State 📝

Unit tests:

Instantiate a Spring State Machine by loading (already existing) .uml file from test folder
Creating a PlantUML text representation of this state machine
Comparing it to to expected result 'see (new) .puml files in test folder)

What does it looks like?

Here are some results (I dumped .puml files to .png):

action-with-transition-choice.uml -> action-with-transition-choice.puml :

multijoin-forkjoin.uml -> multijoin-forkjoin.puml :

Note:
Two *.uml files from test folder leads to inaccurate diagram.
These 2 errors, in simple-connectionpointref.puml and simple-root-regions.puml, are likely to be related to some limitations in spring statemachine UML parser.

Credit: The idea of creating this feature came to me while reading https://github.com/DeveloperUtils/spring-state-machine-chart-dumper

…to illustrate the issue

… image

pivotal-cla · 2024-07-05T08:49:50Z

@pdalfarr Please sign the Contributor License Agreement!

Click here to manually synchronize the status of this Pull Request.

See the FAQ for frequently asked questions.

libinbin880521 · 2024-07-05T08:50:27Z

这是来自QQ邮箱的假期自动回复邮件。您好，我最近正在休假中，无法亲自回复您的邮件。我将在假期结束后，尽快给您回复。

pivotal-cla · 2024-07-05T09:04:26Z

@pdalfarr Thank you for signing the Contributor License Agreement!

pdalfarr · 2024-07-05T15:11:28Z

...emachine-uml/src/test/java/org/springframework/statemachine/plantuml/PlantUmlWriterTest.java

+                // It seems Spring statemachine does not support org.eclipse.uml2.uml.ConnectionPointReference !
+                // Arguments.of("org/springframework/statemachine/uml/simple-connectionpointref", null),


Limitation in Spring state machine ?

pdalfarr · 2024-07-05T15:11:43Z

...emachine-uml/src/test/java/org/springframework/statemachine/plantuml/PlantUmlWriterTest.java

+                // It seems Spring statemachine UML parser creates duplicated transitions!
+                // Arguments.of("org/springframework/statemachine/uml/simple-root-regions", null),


Bug in Spring state machine ?

pdalfarr · 2024-07-05T15:12:20Z

...emachine-uml/src/test/java/org/springframework/statemachine/plantuml/PlantUmlWriterTest.java

+                        new PlantUmlWriterParameters<String>()
+                                .hiddenTransition("S1", RIGHT, "S2")
+                ),
+                Arguments.of("org/springframework/statemachine/uml/simple-guards", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-history-deep", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-history-default", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-history-shallow", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-junction", null),
+                Arguments.of("org/springframework/statemachine/uml/simple-localtransition",
+                        // add some parameters to make diagram more readable
+                        new PlantUmlWriterParameters<String>()
+                                .arrowDirection("S22", UP, "S2")
+                                .arrowDirection("S21", UP, "S2")
+                                .arrowDirection("S22", UP, "S2")
+                                .arrowDirection("S21", UP, "S2")


PlantUmlWriterParameters allow to tweak diagram by 'forcing' direction of some arrows / transitions

… tests resources accordingly

pdalfarr · 2024-07-12T07:00:02Z

Hi @bclozel
I would like some Spring members to tell me if this PR can be useful for the Spring State Machine project or not.
It turns out that you are second in the list of contributors here, hence this message for you 😄
Can I kindly ask you to have a look at this.
I would be happy to elaborate more on why I think this could be useful to the project.
Kind Regards,
Pascal

bclozel · 2024-07-12T07:03:44Z

Hi there!
This is probably a UI bug in GitHub as I don't remember contributing to statemachine and I'm not listed here https://github.com/spring-projects/spring-statemachine/graphs/contributors?from=2015-02-01&to=2024-07-12&type=c

pdalfarr · 2024-07-12T07:08:49Z

...temachine-uml/src/main/java/org/springframework/statemachine/plantuml/helper/NameGetter.java

+	/**
+	 * Implement a 'name strategy' based on this sequence:
+	 * <UL>
+	 * <LI>{@link Expression}</LI>
+	 * <LI>{@link BeanNameAware}</LI>
+	 * <LI>Lambda's unique "arg$1" parameter</LI>
+	 * </UL>
+	 * If all these strategy are failing, fallback to "class name" of the object
+	 *
+	 * @param object object to get "name" from
+	 * @return name of the object
+	 */
+	public static String getName(Object object) {


This class should probably be compared to

spring-statemachine/spring-statemachine-autoconfigure/src/main/java/org/springframework/statemachine/boot/support/BootStateMachineMonitor.java

Lines 137 to 143 in 26ef2bc

private static <S, E> String actionToName(Function<StateContext<S, E>, Mono<Void>> action) {

return ObjectUtils.getDisplayString(action);

}

private static <S, E> String actionFunctionToName(Function<StateContext<S, E>, Mono<Void>> action) {

return ObjectUtils.getDisplayString(action);

}

which seems to be the current mean to get "names" of Spring State Machine actions, guard, etc..

pdalfarr · 2024-07-12T11:11:58Z

@bclozel
Thanks for your reply.
Yes, this is likely a bug: your avatar is visible in second position on main page of the project and you did not contribute indeed.

I see you are a committer on some Spring projects, so I take the opportunity to ask you this: how I can do to reach out to Spring State Machine "owner(s)" ?
It looks like many PR are waiting here (not only mine) and I do not see much activity in Spring State Machine GitHub project.
Should we (user of Spring State Mchine) worry about this?
Is Spring State Machine still properly maintained?

( ? Maybe someone at Pivotal / VMWare could help regarding my questions ? )

bclozel · 2024-07-12T12:49:22Z

I think @jvalkeal knows.

pdalfarr · 2024-07-12T13:00:45Z

Hi @jvalkeal

Who can I reach out to, to discuss this PR?

Thanks

… make 'Connection' cComparable

pdalfarr · 2024-10-21T12:58:20Z

@fmbenhassine , we can discuss this whenever you want ;-)

pdalfarr · 2025-03-11T14:55:05Z

Hi @fmbenhassine !
Thanks for your kind message :-)

I just made a change.
Is this OK with net.sourceforge.plantuml:plantuml-asl:1.2025.2?
Cfr f8507fb

( see https://sakirtemel.github.io/plantuml-alternative-docs/docs/main/faq.html#_i_dont_like_gpl )

Signed-off-by: Pascal Dal Farra <[email protected]>

…to illustrate the issue Signed-off-by: Pascal Dal Farra <[email protected]>

Signed-off-by: Pascal Dal Farra <[email protected]>

… image Signed-off-by: Pascal Dal Farra <[email protected]>

Signed-off-by: Pascal Dal Farra <[email protected]>

… tests resources accordingly Signed-off-by: Pascal Dal Farra <[email protected]>

Signed-off-by: Pascal Dal Farra <[email protected]>

… make 'Connection' cComparable Signed-off-by: Pascal Dal Farra <[email protected]>

Signed-off-by: Pascal Dal Farra <[email protected]>

pdalfarr · 2025-03-12T08:36:56Z

@fmbenhassine I am trying to fix "DCO Action required after 1s — DCO" regarding Signed-off-by: Author Name [email protected], but it looks like the changes I made are not taken into account.

On my side, I now see the required Signed-off on my commits, but the DCO issue is still listed here :/
I am afraid I wasn't able to fix this, and I must confess I don't know how to do

cfr

fmbenhassine · 2025-03-13T12:56:51Z

Thank you for your feedback! The DCO issue is due to the fact that there are some commits among the 41 commits in that PR that are not signed off. You will need to squash all commits anyway.

Is this OK with net.sourceforge.plantuml:plantuml-asl:1.2025.2?

Yes, we can use that as long as the source code is available. Where is the source code of that module? We need the source code, not only a binary dependency. I also took some time to review the PR, and we need some updates:

Please remove Lombok usage and replace it with Java records (use regular classes if you need mutability)
The feature is about generating PlantUML diagrams and should focus on that. The code that generates images should be separate from that feature (one may ask why png and not jpeg?). This can be a utility class separate from the one that is related to the main feature. We can even have a separate PR that adds the ability to generate images from PlantUML diagrams as well as the existing Papyrus UML diagrams.
Please add javadocs to public APIs (at least the main methods of the feature that users will use the most).

Please let me know if I can help on any of these.

Apart from that, I just wanted to mention that we have no plan to ship a feature release for v4 for the moment (only bug fixes are planned for now). So this PR will target v5 at a minimum.

pdalfarr · 2025-03-13T13:20:58Z

Thanks for your feedback.

Source jar for plantuml-asl-1.2025.2.jar is available here :
https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml-asl/1.2025.2/
https://repo1.maven.org/maven2/net/sourceforge/plantuml/plantuml-asl/1.2025.2/plantuml-asl-1.2025.2-sources.jar
Okay, I'll remove Lombok.
I'll (re)move png generation feature and probably create a dedicated PR for it. This makes sense.
Javadoc addition on public API: Roger that!

Thanks for the clarification on which version of SSM will likely ship this pull request 👍

Signed-off-by: Pascal Dal Farra <[email protected]>

Pascal Dal Farra added 6 commits March 4, 2024 16:35

test: add testStateMachineVsStateMachineModelConsistency()

5f7a0e9

test: testStateMachineVsStateMachineModelConsistency() add png image …

79eb82a

…to illustrate the issue

test: testStateMachineVsStateMachineModelConsistency() update png

2d07152

test: testStateMachineVsStateMachineModelConsistency() update javadoc…

3a496b4

… image

Merge branch 'main' of https://github.com/pdalfarr/spring-statemachine

b7d2387

feat: add PlantUml rendering feature

1381468

pdalfarr changed the title ~~PlantUML visualization~~ New Feature - PlantUML visualization Jul 5, 2024

feat: illustrate use of hiddenTransitions

238be9c

pdalfarr commented Jul 5, 2024

View reviewed changes

Pascal Dal Farra added 6 commits July 9, 2024 15:48

fix: fix NPE

1fca598

fix: Fix TransitionComparator

5f1a4f4

fix: Fix TransitionComparator

a7b2add

chore: code cleaning

961f5ce

feat: add global diagram settings + update arrow colors + update unit…

59df160

… tests resources accordingly

chore: Add Apache license header

935fa33

pdalfarr commented Jul 12, 2024

View reviewed changes

Pascal Dal Farra added 2 commits July 17, 2024 16:00

chore: make attributes private

bbab08e

feat: improve NameGetter (AopProxyUtils) + add 'ignoredTransitions' +…

ceecb4e

… make 'Connection' cComparable

feat: add arrow length parameter

42ccaa4

pdalfarr force-pushed the main branch 2 times, most recently from 4dd42f9 to b58a330 Compare March 12, 2025 07:20

fix: fix collectAllStates() typo + bump to plantuml-asl-1.2025.2

b9f3ef7

Signed-off-by: Pascal Dal Farra <[email protected]>

pdalfarr force-pushed the main branch from b58a330 to b9f3ef7 Compare March 12, 2025 07:23

Pascal Dal Farra and others added 20 commits March 12, 2025 08:45

test: testStateMachineVsStateMachineModelConsistency() add png image …

f17dcd9

…to illustrate the issue Signed-off-by: Pascal Dal Farra <[email protected]>

test: testStateMachineVsStateMachineModelConsistency() update png

73437d0

Signed-off-by: Pascal Dal Farra <[email protected]>

test: testStateMachineVsStateMachineModelConsistency() update javadoc…

6c58ace

… image Signed-off-by: Pascal Dal Farra <[email protected]>

feat: add PlantUml rendering feature

5e34b86

Signed-off-by: Pascal Dal Farra <[email protected]>

feat: illustrate use of hiddenTransitions

7efd7d9

Signed-off-by: Pascal Dal Farra <[email protected]>

fix: fix NPE

b101283

Signed-off-by: Pascal Dal Farra <[email protected]>

fix: Fix TransitionComparator

5631a8e

Signed-off-by: Pascal Dal Farra <[email protected]>

fix: Fix TransitionComparator

2afe0dd

Signed-off-by: Pascal Dal Farra <[email protected]>

chore: code cleaning

ed95830

Signed-off-by: Pascal Dal Farra <[email protected]>

feat: add global diagram settings + update arrow colors + update unit…

fe58235

… tests resources accordingly Signed-off-by: Pascal Dal Farra <[email protected]>

chore: Add Apache license header

07ba7c4

Signed-off-by: Pascal Dal Farra <[email protected]>

chore: make attributes private

92bbacb

Signed-off-by: Pascal Dal Farra <[email protected]>

feat: improve NameGetter (AopProxyUtils) + add 'ignoredTransitions' +…

bc84234

… make 'Connection' cComparable Signed-off-by: Pascal Dal Farra <[email protected]>

feat: add arrow length parameter

7f9a27e

Signed-off-by: Pascal Dal Farra <[email protected]>

chore: keep hiddenTransitions sorted + fix getArrowLength

aaecace

Signed-off-by: Pascal Dal Farra <[email protected]>

feat: add PlantUmlWriterParameters.note()

00048f3

Signed-off-by: Pascal Dal Farra <[email protected]>

feat: add PlantUmlWriterParameters.note() - update png

eaec709

Signed-off-by: Pascal Dal Farra <[email protected]>

fix: fix collectAllStates() typo + bump to plantuml-asl-1.2025.2

c81786e

Signed-off-by: Pascal Dal Farra <[email protected]>

Merge branch 'main' of https://github.com/pdalfarr/spring-statemachine

2215b1b

Merge branch 'spring-projects:main' into main

a5c8b6e

fmbenhassine added this to the 5.0.x milestone Mar 13, 2025

chore: remove lombok dependency

39de9c4

Signed-off-by: Pascal Dal Farra <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🥳 New Feature 🥳 PlantUML visualization #1158

🥳 New Feature 🥳 PlantUML visualization #1158

pdalfarr commented Jul 5, 2024 •

edited

Loading

pivotal-cla commented Jul 5, 2024

libinbin880521 commented Jul 5, 2024 via email

pivotal-cla commented Jul 5, 2024

pdalfarr Jul 5, 2024

pdalfarr Jul 5, 2024

pdalfarr Jul 5, 2024

pdalfarr commented Jul 12, 2024

bclozel commented Jul 12, 2024

pdalfarr Jul 12, 2024

pdalfarr commented Jul 12, 2024

bclozel commented Jul 12, 2024

pdalfarr commented Jul 12, 2024

pdalfarr commented Oct 21, 2024

pdalfarr commented Mar 11, 2025 •

edited

Loading

pdalfarr commented Mar 12, 2025 •

edited

Loading

fmbenhassine commented Mar 13, 2025

pdalfarr commented Mar 13, 2025

	public String getArrowColor(boolean isCurrentTransaction) {
	return isCurrentTransaction ? "[#FF0000]" : "";
	}

		// It seems Spring statemachine does not support org.eclipse.uml2.uml.ConnectionPointReference !
		// Arguments.of("org/springframework/statemachine/uml/simple-connectionpointref", null),

		// It seems Spring statemachine UML parser creates duplicated transitions!
		// Arguments.of("org/springframework/statemachine/uml/simple-root-regions", null),

	private static <S, E> String actionToName(Function<StateContext<S, E>, Mono<Void>> action) {
	return ObjectUtils.getDisplayString(action);
	}

	private static <S, E> String actionFunctionToName(Function<StateContext<S, E>, Mono<Void>> action) {
	return ObjectUtils.getDisplayString(action);
	}

🥳 New Feature 🥳 PlantUML visualization #1158

Are you sure you want to change the base?

🥳 New Feature 🥳 PlantUML visualization #1158

Conversation

pdalfarr commented Jul 5, 2024 • edited Loading

pivotal-cla commented Jul 5, 2024

libinbin880521 commented Jul 5, 2024 via email

pivotal-cla commented Jul 5, 2024

pdalfarr Jul 5, 2024

Choose a reason for hiding this comment

pdalfarr Jul 5, 2024

Choose a reason for hiding this comment

pdalfarr Jul 5, 2024

Choose a reason for hiding this comment

pdalfarr commented Jul 12, 2024

bclozel commented Jul 12, 2024

pdalfarr Jul 12, 2024

Choose a reason for hiding this comment

pdalfarr commented Jul 12, 2024

bclozel commented Jul 12, 2024

pdalfarr commented Jul 12, 2024

pdalfarr commented Oct 21, 2024

pdalfarr commented Mar 11, 2025 • edited Loading

pdalfarr commented Mar 12, 2025 • edited Loading

fmbenhassine commented Mar 13, 2025

pdalfarr commented Mar 13, 2025

pdalfarr commented Jul 5, 2024 •

edited

Loading

pdalfarr commented Mar 11, 2025 •

edited

Loading

pdalfarr commented Mar 12, 2025 •

edited

Loading